---
title: Dialog
description: Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks. A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.
docType: Demo
docGroup: Components
group: Feedback
alias: [Modal, Alert, Popover]
components:
  [Dialog, DialogHeader, DialogTitle, DialogContent, DialogFooter, FixedDialog]
---

# Dialog

Dialogs inform users about a task and can contain critical information, require
decisions, or involve multiple tasks.

A dialog is a type of modal window that appears in front of app content to
provide critical information or ask for a decision. Dialogs disable all app
functionality when they appear, and remain on screen until confirmed, dismissed,
or a required action has been taken.

## Simple Example

A dialog can be created using the `Dialog`, `DialogHeader`, `DialogTitle`,
`DialogContent`, and `DialogFooter` components. The `Dialog` is a controlled
component requiring a `visible` state, `onRequestClose` function to close the
dialog, and either an `aria-label` or `aria-labelledby` for accessibility.

A common pattern is to set the `aria-labelledby` to the `DialogTitle` since the
title would normally describe the purpose of the dialog.

```demo source="./SimpleExample.tsx"

```

### Full Page Dialog

A dialog can span the entire viewport by setting the `type` to `"full-page"`.

```demo source="./FullPageDialogExample.tsx"

```

## Dialog Widths

The `Dialog` can be updated to enforce a specific width instead of relying on
the size of the content using the `width` prop. The available values are:

- `"auto"` (default) - width is based on content
- `"small"` - uses `var(--rmd-dialog-small-width)` and configured by
  [$SASSDOC](dialog-small-width) or [$SASSDOC](<dialog-set-var(small-width, NEW_VALUE)>)
- `"medium"` - uses `var(--rmd-dialog-medium-width)` and configured by
  [$SASSDOC](dialog-medium-width) or [$SASSDOC](<dialog-set-var(medium-width, NEW_VALUE)>)
- `"large"` - uses `var(--rmd-dialog-large-width)` and configured by
  [$SASSDOC](dialog-large-width) or [$SASSDOC](<dialog-set-var(large-width, NEW_VALUE)>)
- `"extra-large"` - uses `var(--rmd-dialog-extra-large-width)` and configured
  by [$SASSDOC](dialog-extra-large-width) or [$SASSDOC](<dialog-set-var(extra-large-width, NEW_VALUE)>)

```demo source="./DialogWidths.tsx"

```

## Modal Dialog

The default behavior for the dialog is to allow the user to click the overlay to
close the dialog. If the user should be forced to interact with the modal to
close it, enable the `modal` prop.

When the `modal` prop is enabled, the `role` should normally switch to an
[alertdialog](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role)
to increase the accessibility. An `aria-describedby` should also be set on the
dialog to describe the alert.

```demo source="./ModalDialogExample.tsx"

```

## Fixed Dialog

If a dialog should be positioned relative to another element, use the
`FixedDialog` component. The `FixedDialog` component maintains the same API as
the `Dialog` component with a few changes:

- a new `fixedTo` ref prop is required to position itself to another element
  - the default anchor is set to `TOP_INNER_RIGHT_ANCHOR`
- the CSS transition defaults to using a scale transition
- the overlay is hidden by default
- the page is scrollable while the dialog is visible by default
  - the dialog will automatically hide if the user scrolls the dialog out of
    view
  - the `fixedTo` element is not re-focused for this flow

```demo source="./FixedDialogExample.tsx"

```

## Setting the Initial Focus

When the dialog gains visibility, the current focus will move to the dialog
itself and trap focus within the dialog. If another element in the dialog should
gain focus instead, enable the `autoFocus` prop on that element.

```demo source="./SettingInitialFocusExample.tsx"

```

## Custom Transition

The `Dialog` uses the [useCSSTransition](/hooks/use-css-transition) to handle
the visibility transitions and can be customized by providing the `timeout` and
`classNames` props.

```demo source="./CustomTransitionExample.tsx"

```

## Nested Dialogs

Dialogs can be nested without any additional setup since the dialogs are
portalled behind the scenes and only the topmost overlay will be shown at a
time.

> !Info! If multiple overlays were shown at the same time, the overlay would
> become darker as more dialogs are shown which can cause performance issues on
> mobile devices.

```demo source="./NestedDialogsExample.tsx"

```

### Nested Dialogs Default Visible

If nested dialogs should be visible by on initial page load or mount, trigger
the `show` behavior into a `useEffect` instead of setting the initial state to
`true`. If multiple dialogs are rendered at once, the topmost dialog will be
shown instead of the child dialogs due to how React renders.

```demo source="./NestedDialogsVisibleExample.tsx"

```
